随笔

📋 文档概览

本文档涵盖以下完整流程：

Claude Code - Windows Native Install 安装配置
NewAPI - Linux 服务器 Docker 部署（外接 MySQL/PostgreSQL 数据库）
对接配置 - 使用 NewAPI 作为 Claude Code 的 API 代理网关

第一部分：Windows 安装 Claude Code (Native Install)

1.1 系统要求

组件	要求
操作系统	Windows 10 或更高版本
内存	最低 4GB（推荐 16GB）
磁盘空间	500MB 可用空间
必需软件	Git for Windows[1]

⚠️ 重要提示: Windows 用户必须预先安装 Git for Windows，因为 Claude Code 依赖于 Unix-like 环境。

1.2 安装步骤

方式一：PowerShell 安装（推荐）

在 Windows PowerShell（管理员权限）中执行：

# PowerShell 安装脚本
irm https://claude.ai/install.ps1 | iex

方式二：CMD 安装

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

方式三：Winget 安装

winget install Anthropic.ClaudeCode

1.3 验证安装

# 验证安装
claude --version

1.4 首次配置

启动 Claude Code:

claude

登录账户:
- 首次启动会提示登录
- 支持 Claude Pro/Max/Teams/Enterprise 或 Claude Console 账户[1]
- 也可使用 /login 命令重新登录
配置环境变量（可选）:

如果使用第三方 API 代理（如 NewAPI），配置以下环境变量：

# 临时配置（当前终端生效）
$env:ANTHROPIC_API_KEY="sk-your-api-key"
$env:ANTHROPIC_BASE_URL="https://your-newapi-endpoint.com"
$env:ANTHROPIC_MODEL="claude-4-opus-20250514"

# 或者修改配置文件（推荐）
Setx ANTHROPIC_API_KEY "sk-your-api-key"
Setx ANTHROPIC_BASE_URL "https://your-newapi-endpoint.com"
Setx ANTHROPIC_MODEL "claude-4-opus-20250514"

💡 提示: 配置完成后需重新打开终端使变量生效。

第二部分：Linux 服务器部署 NewAPI（外接数据库）

2.1 部署要求

组件	要求
服务器系统	Ubuntu 20.04+/Debian 10+/CentOS 7+
Docker	已安装 Docker & Docker Compose
外部数据库	MySQL ≥ 5.7.8 或 PostgreSQL ≥ 9.6
端口	3000（可配置）

2.2 数据库准备

MySQL 配置

-- 创建数据库和用户
CREATE DATABASE new_api DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'newapi_user'@'%' IDENTIFIED BY 'YourSecurePassword';
GRANT ALL PRIVILEGES ON new_api.* TO 'newapi_user'@'%';
FLUSH PRIVILEGES;

PostgreSQL 配置

-- 创建数据库和用户
CREATE DATABASE new_api;
CREATE USER newapi_user WITH ENCRYPTED PASSWORD 'YourSecurePassword';
GRANT ALL PRIVILEGES ON DATABASE new_api TO newapi_user;

2.3 Docker Compose 部署

mkdir -p /opt/newapi
cd /opt/newapi

创建 docker-compose.yml:

version: "3"

services:
  new-api:
    image: calciumion/new-api:latest
    container_name: new-api
    restart: always
    ports:
      - "3000:3000"
    environment:
      # 核心配置
      SQL_DSN: "newapi_user:YourSecurePassword@tcp(mysql-server:3306)/new_api"  # MySQL
      # SQL_DSN: "postgres://newapi_user:YourSecurePassword@postgres-server:5432/new_api"  # PostgreSQL
    
      # 会话密钥（多机部署必设）
      SESSION_SECRET: "your-random-session-secret-string-min-32-chars"
    
      # 可选 Redis 缓存
      REDIS_CONN_STRING: "redis://redis-server:6379"
      CRYPTO_SECRET: "your-redis-crypto-secret"
    
      # 时区配置
      TZ: "Asia/Shanghai"
    
      # 其他常用配置
      STREAMING_TIMEOUT: "300"
      MAX_REQUEST_BODY_MB: "32"
      ERROR_LOG_ENABLED: "true"
    
    volumes:
      - ./data:/data
  
    # 如果使用外部数据库，不需要 depends_on
    # 如果使用容器化数据库，添加依赖
    # depends_on:
    #   - mysql
    #   - redis

# 可选：如果需要容器化数据库
#   mysql:
#     image: mysql:8.0
#     container_name: newapi-mysql
#     restart: always
#     environment:
#       MYSQL_ROOT_PASSWORD: root-password
#       MYSQL_DATABASE: new_api
#       MYSQL_USER: newapi_user
#       MYSQL_PASSWORD: YourSecurePassword
#     volumes:
#       - mysql_data:/var/lib/mysql
#     ports:
#       - "3306:3306"

#   redis:
#     image: redis:alpine
#     container_name: newapi-redis
#     restart: always
#     volumes:
#       - redis_data:/data

# volumes:
#   mysql_data:
#   redis_data:

启动服务:

# 拉取镜像
docker-compose pull

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

验证部署:

# 检查容器状态
docker ps | grep new-api

# 测试 API 可用性
curl http://localhost:3000/api/status

2.4 关键环境变量说明[2]

变量名	说明	是否必填
`SQL_DSN`	数据库连接字符串（MySQL/PostgreSQL）	✅ 是（外部数据库）
`SESSION_SECRET`	会话密钥，多机部署必设	✅ 是
`CRYPTO_SECRET`	Redis 加密密钥，使用 Redis 时必设	Redis 场景必填
`REDIS_CONN_STRING`	Redis 连接字符串	可选（推荐）
`STREAMING_TIMEOUT`	流式超时时间（秒）	可选，默认 300
`MAX_REQUEST_BODY_MB`	请求体最大大小（MB）	可选，默认 32
`ERROR_LOG_ENABLED`	错误日志开关	可选，默认 false

2.5 数据库连接字符串格式

MySQL:

user:password@tcp(host:port)/dbname

PostgreSQL:

postgres://user:password@host:port/dbname

示例:

# MySQL
SQL_DSN: "root:123456@tcp(192.168.1.100:3306)/new_api"

# 带参数的 MySQL
SQL_DSN: "root:123456@tcp(192.168.1.100:3306)/new_api?charset=utf8mb4&parseTime=True"

# PostgreSQL
SQL_DSN: "postgres://postgres:password@192.168.1.100:5432/new_api?sslmode=disable"

第三部分：Claude Code + NewAPI 对接配置

3.1 NewAPI 初始化配置

访问 NewAPI 管理后台:

http://your-newapi-server:3000

首次登录:
- 默认账号: root
- 默认密码: 123456（请及时修改）
配置 Claude 渠道:
- 进入 渠道管理 → 添加渠道
- 选择渠道类型: Anthropic Claude
- 填入真实的 Anthropic API Key
- 配置代理域名（如使用反向代理）
创建令牌:
- 进入 令牌管理 → 添加令牌
- 设置额度、有效期和可用模型
- 复制生成的令牌供 Claude Code 使用

3.2 Windows Claude Code 配置

方法一：环境变量配置

# 设置 NewAPI 作为 API 基础地址
$env:ANTHROPIC_BASE_URL = "http://your-newapi-server:3000/v1"
$env:ANTHROPIC_API_KEY = "sk-newapi-token-here"

# 启动 Claude Code
claude

方法二：配置文件持久化

在 PowerShell 配置文件中添加：

# 添加到 $PROFILE
notepad $PROFILE

添加内容：

# Claude Code + NewAPI 配置
$env:ANTHROPIC_BASE_URL = "http://your-newapi-server:3000/v1"
$env:ANTHROPIC_API_KEY = "sk-newapi-token-here"
$env:ANTHROPIC_MODEL = "claude-4-opus-20250514"

方法三：单次启动配置

# 启动时直接指定环境变量
$env:ANTHROPIC_BASE_URL="http://192.168.1.100:3000/v1"; $env:ANTHROPIC_API_KEY="sk-xxxx"; claude

3.3 完整配置示例

# Windows 环境完整配置脚本

# Claude Code API 配置
$env:ANTHROPIC_API_KEY = "sk-newapi-generated-token"
$env:ANTHROPIC_BASE_URL = "http://your-newapi-domain.com/v1"
$env:ANTHROPIC_MODEL = "claude-4-opus-20251514"

# 可选的高级配置
$env:CLAUDE_MAX_TOKENS = "4096"
$env:CLAUDE_TEMPERATURE = "0.7"
$env:CLAUDE_TIMEOUT = "300"

# 启动 Claude Code
claude

3.4 验证对接

在 Claude Code 中测试:

请检查当前配置的 API 端点是什么？

在 NewAPI 后台查看:
- 进入 日志管理 查看请求记录
- 检查令牌使用量和消费日志
使用测试命令:

# 测试连接
claude -p "Hello, can you confirm you're connected through the API gateway?"

第四部分：高级配置

4.1 Nginx 反向代理配置（生产环境）

server {
    listen 443 ssl;
    server_name api.yourdomain.com;

    ssl_certificate /path/to/your/certificate.crt;
    ssl_certificate_key /path/to/your/private.key;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
      
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
      
        # WebSocket 支持（用于流式输出）
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
      
        # 超时配置
        proxy_read_timeout 300s;
        proxy_connect_timeout 300s;
        proxy_send_timeout 300s;
    }
}

4.2 防火墙配置

# Linux 服务器防火墙放行
sudo ufw allow 3000/tcp

# 或仅允许特定 IP
sudo ufw allow from 192.168.1.0/24 to any port 3000

# 如果使用反向代理（推荐）
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

4.3 NewAPI 多机部署注意事项[2]

⚠️ 多机部署必设环境变量:

SESSION_SECRET: 所有节点使用相同的会话密钥
CRYPTO_SECRET: 使用 Redis 时必设相同的加密密钥

# 多机部署示例
services:
  new-api-node1:
    image: calciumion/new-api:latest
    environment:
      SESSION_SECRET: "same-session-secret-for-all-nodes"
      CRYPTO_SECRET: "same-crypto-secret-for-all-nodes"
      SQL_DSN: "..."
      REDIS_CONN_STRING: "redis://shared-redis:6379"

  new-api-node2:
    image: calciumion/new-api:latest
    environment:
      SESSION_SECRET: "same-session-secret-for-all-nodes"  # 相同
      CRYPTO_SECRET: "same-crypto-secret-for-all-nodes"    # 相同
      SQL_DSN: "..."
      REDIS_CONN_STRING: "redis://shared-redis:6379"

第五部分：故障排查

5.1 Claude Code 常见问题

问题	解决方案
`无法找到 claude 命令`	检查 PATH 环境变量，或重新安装
`Git for Windows 未安装`	安装 https://git-scm.com/downloads/win
`权限错误 (EACCES)`	不要使用 sudo 安装，修复 npm 权限
`SSL 连接失败`	检查公司防火墙或代理设置

5.2 NewAPI 常见问题

问题	解决方案
`数据库连接失败`	检查 SQL_DSN 格式和网络连通性
`容器无法启动`	查看日志 `docker-compose logs`
`登录状态不一致`	设置 SESSION_SECRET
`Redis 数据无法解密`	设置 CRYPTO_SECRET

5.3 对接问题排查

# 测试 API 连通性
Invoke-RestMethod -Uri "http://your-newapi-server:3000/api/status" -Method GET

# 检查 Claude Code 环境变量
Get-ChildItem Env: | Where-Object { $_.Name -like "*ANTHROPIC*" }

# NewAPI 容器日志
docker-compose logs --tail 100 new-api

第六部分：安全建议

6.1 生产环境安全检查清单

修改默认管理员密码
使用 HTTPS（配置 SSL/TLS）
设置强密码的数据库账号
配置 SESSION_SECRET 和 CRYPTO_SECRET
限制 NewAPI 端口访问（仅允许内网/VPN）
定期备份数据库
启用 NewAPI 日志记录
配置 IP 白名单（如有必要）

6.2 Token 安全

# 使用环境变量存储敏感信息（不要将密钥写入代码）
# 避免将密钥提交到 Git
# 定期轮换 API Token

# Windows 正确做法
$env:ANTHROPIC_API_KEY = Get-Content "~\.anthropic\api_key.txt" -Raw

参考文档

Claude Code 官方文档 - [https://code.claude.com/docs/zh-CN/quickstart][1]
NewAPI GitHub 文档 - [https://github.com/QuantumNous/new-api/blob/main/README.zh_CN.md][2]

ABOUT ME

随笔

👉标签

Claude Code (Windows) + NewAPI (Linux) 完整对接文档

📋 文档概览

第一部分：Windows 安装 Claude Code (Native Install)

1.1 系统要求

1.2 安装步骤

方式一：PowerShell 安装（推荐）

方式二：CMD 安装

方式三：Winget 安装

1.3 验证安装

1.4 首次配置

第二部分：Linux 服务器部署 NewAPI（外接数据库）

2.1 部署要求

2.2 数据库准备

MySQL 配置

PostgreSQL 配置

2.3 Docker Compose 部署

2.4 关键环境变量说明[2]

2.5 数据库连接字符串格式

第三部分：Claude Code + NewAPI 对接配置

3.1 NewAPI 初始化配置

3.2 Windows Claude Code 配置

方法一：环境变量配置

方法二：配置文件持久化

方法三：单次启动配置

3.3 完整配置示例

3.4 验证对接

第四部分：高级配置

4.1 Nginx 反向代理配置（生产环境）

4.2 防火墙配置

4.3 NewAPI 多机部署注意事项[2]

第五部分：故障排查

5.1 Claude Code 常见问题

5.2 NewAPI 常见问题

5.3 对接问题排查

第六部分：安全建议

6.1 生产环境安全检查清单

6.2 Token 安全

参考文档

Antigravity反代实现Claude模型自由